Amiga Format CD 36

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Format CD 36 / Amiga Format CD36 (1999-01-22)(Future Publishing)(GB)[!][issue 1999-02].iso / -seriously_amiga- / graphics / gfx3d.library / docs / autodocs.txt next >

Wrap

Text File | 1998-12-12 | 51KB | 2,361 lines

----------------------------------------------------------------------------- gfx3d.library v2.x AUTODOCS ----------------------------------------------------------------------------- Lista delle funzioni della libreria ordinata alfabeticamente: gfx3d.library/GFXAbs gfx3d.library/GFXAdd gfx3d.library/GFXAllocMem gfx3d.library/GFXAspectRatio gfx3d.library/GFXBegin gfx3d.library/GFXClearWorkBuffer gfx3d.library/GFXColor gfx3d.library/GFXCos gfx3d.library/GFXDirection gfx3d.library/GFXDiv gfx3d.library/GFXEnd gfx3d.library/GFXEnvironment gfx3d.library/GFXFarClip gfx3d.library/GFXFeatures gfx3d.library/GFXFix gfx3d.library/GFXFixMul gfx3d.library/GFXFixSqrt gfx3d.library/GFXFlt gfx3d.library/GFXFltMul gfx3d.library/GFXFocus gfx3d.library/GFXFrame gfx3d.library/GFXFreeMem gfx3d.library/GFXHeight gfx3d.library/GFXModifyCameraAspectRatio gfx3d.library/GFXModifyCameraDirection gfx3d.library/GFXModifyCameraFocus gfx3d.library/GFXModifyCameraHeight gfx3d.library/GFXModifyCameraPosition gfx3d.library/GFXModifyCameraVideoBuffer gfx3d.library/GFXModifyCameraWidth gfx3d.library/GFXModifyObjectDirection gfx3d.library/GFXModifyObjectFrame gfx3d.library/GFXModifyObjectPosition gfx3d.library/GFXMul gfx3d.library/GFXNearClip gfx3d.library/GFXNeg gfx3d.library/GFXObject gfx3d.library/GFXPalette gfx3d.library/GFXPi gfx3d.library/GFXPolygon gfx3d.library/GFXPosition gfx3d.library/GFXSetColor gfx3d.library/GFXSetFarClip gfx3d.library/GFXSetNearClip gfx3d.library/GFXSetShading gfx3d.library/GFXShadeTable gfx3d.library/GFXShading gfx3d.library/GFXShareWorkBuffer gfx3d.library/GFXSin gfx3d.library/GFXSqrt gfx3d.library/GFXSteps gfx3d.library/GFXSub gfx3d.library/GFXThreshold gfx3d.library/GFXUpdateScene gfx3d.library/GFXUpdateVideoBuffer gfx3d.library/GFXVersion gfx3d.library/GFXVertex gfx3d.library/GFXVideoBuffer gfx3d.library/GFXWidth gfx3d.library/GFXWritePixel ----------------------------------------------------------------------------- gfx3d.library/GFXAbs SINTASSI result = GFXAbs (value) D0 D0 SCOPO Questa funzione serve per calcolare il valore assoluto di un numero reale (rappresentato nel formato interno della libreria). ARGOMENTI value = valore in formato reale. RISULTATO result = valore assoluto, in formato reale, del valore dato in ingresso. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXAdd SINTASSI result = GFXAdd (value1, value2) D0 D1 D0 SCOPO Questa funzione restituisce la somma di due numeri reali (rappresentati nel formato interno della libreria). ARGOMENTI value1 = valore in formato reale. value2 = valore in formato reale. RISULTATO result = somma, in formato reale, dei due numeri presenti in ingresso. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXAllocMem SINTASSI memptr = GFXAllocMem (bytesize) D0 D0 SCOPO Questa funzione alloca un quantitativo di memoria pubblica del sistema. La funzione restituisce l'indirizzo del blocco di memoria allocato oppure il valore GFX_NULL in caso di insuccesso. ARGOMENTI bytesize = dimensione in bytes del blocco di memoria pubblica da allocare. RISULTATO result = indirizzo del blocco di memoria pubblica allocato. DISCUSSIONE Questa funzione è utilizzata per allocare un determinato quantitativo di memoria del sistema. Non è necessario doversi ricordare l'indirizzo ottenuto dalla funzione (a meno di non dover deallocare successivamente il blocco tramite la funzione GFXFreeMem()), in quanto il gestore della memoria interno alla libreria utilizza un memory pool, il quale si occupa di deallocare tutta la memoria allocata dal task tramite le chiamate alla funzione GFXAllocMem() all'uscita della libreria. Si noti che la memoria allocata dalla funzione è pubblica, ovvero Fast RAM in presenza di un'espansione. Questo implica che tutti i dati che devono risiedere in Chip RAM (bitplanes, dati audio, ecc...) devono venire allocati e deallocati dal task con le funzioni di sistema appropriate. ----------------------------------------------------------------------------- gfx3d.library/GFXAspectRatio SINTASSI GFXAspectRatio (ratiox, ratioy, ratioz) D0 D1 D2 SCOPO Questa funzione setta il fattore moltiplicativo della telecamera che si sta definendo. ARGOMENTI ratiox = valore reale per cui moltiplicare le coordinate X dei vertici presenti nella scena prima della proiezione a video. ratioy = valore reale per cui moltiplicare le coordinate Y dei vertici presenti nella scena prima della proiezione a video. ratioz = valore reale per cui moltiplicare le coordinate Z dei vertici presenti nella scena prima della proiezione a video. DISCUSSIONE Questa funzione consente di settare l'aspetto della scena visualizzata dalla telecamera. Ad esempio, per visualizzare con le corrette proporzioni una scena su uno schermo HiRes, occorre settare l'aspect ratio della telecamera nel seguente modo: GFXAspectRatio( GFXFlt( 2 ), GFXFlt( 1 ), GFXFlt( 1 ) ); in quanto i pixel presentano il caratteristico aspetto rettangolare 1:2. Poichè i vertici subiscono la moltiplicazione dovuta all'aspetto prima di essere proiettati a video, cioè quando sono espressi ancora in Camera Coordinates, è possibile, variando opportunamente l'aspetto delle coordinate Y, implementare l'effetto zoom di una telecamera. ----------------------------------------------------------------------------- gfx3d.library/GFXBegin SINTASSI GFXBegin (structType) D0 SCOPO Questa funzione definisce il tipo di struttura dati i cui parametri verranno definiti dalle successive funzioni. ARGOMENTI structType = tipo di struttura dati da definire: - GFX_POLYGON - GFX_FRAME - GFX_OBJECT - GFX_ENVIRONMENT - GFX_CAMERA - GFX_SHADETABLE DISCUSSIONE Questa funzione viene utilizzata per iniziare un blocco di definizione di una determinata struttura dati della libreria. Una sequenza di definizione di una struttura dati inizia sempre con una chiamata alla funzione GFXBegin() e si conclude sempre con una chiamata alla funzione GFXEnd(). Le sequenze di definizione possono anche essere innestate. Ad esempio, le seguenti istruzioni definiscono un triangolo: GFXBegin( GFX_POLYGON ); GFXVertex( x0, y0, z0 ); GFXVertex( x1, y1, z1 ); GFXVertex( x2, y2, z2 ); triangle = GFXEnd(); mentre le seguenti istrizioni definiscono un frame con due triangoli: GFXBegin( GFX_FRAME ); GFXBegin( GFX_POLYGON ); GFXVertex( x2, y2, z2 ); GFXVertex( x1, y1, z1 ); GFXVertex( x0, y0, z0 ); GFXPolygon( GFXEnd() ); GFXPolygon( triangle ); frame = GFXEnd(); ----------------------------------------------------------------------------- gfx3d.library/GFXClearWorkBuffer SINTASSI GFXClearWorkBuffer () SCOPO Questa funzione pulisce il work buffer attualmente in uso. DISCUSSIONE Questa funzione si occupa di pulire il buffer di lavoro corrente, riempendolo con il valore 0. In genere, questa funzione va chiamata dopo la funzione GFXUpdateVideoBuffer(). ----------------------------------------------------------------------------- gfx3d.library/GFXColor SINTASSI GFXColor (color) D0 SCOPO Questa funzione definisce il colore da associare alla struttura dati che si sta definendo. ARGOMENTI color = colore da associare alla struttura dati in definizione. DISCUSSIONE Questa funzione viene utilizzata per definire il colore da associare alla struttura dati che si sta definendo. La funzione va quindi chiamata all'interno di una sezione di definizione. ----------------------------------------------------------------------------- gfx3d.library/GFXCos SINTASSI value = GFXCos (angle) D0 D0 SCOPO Questa funzione restituisce il coseno dell'angolo dato in ingresso. ARGOMENTI angle = valore reale esprimente l'angolo in radianti. RISULTATO result = valore reale esprimente il coseno dell'angolo dato. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXDirection SINTASSI GFXDirection (ax, ay, az) D0 D1 D2 SCOPO Questa funzione definisce la direzione da associare alla struttura dati che si sta definendo. ARGOMENTI ax = valore intero esprimente l'angolo di rotazione attorno l'asse X. ay = valore intero esprimente l'angolo di rotazione attorno l'asse Y. az = valore intero esprimente l'angolo di rotazione attorno l'asse Z. DISCUSSIONE Questa funzione viene utilizzata per definire la direzione da associare alla struttura dati che si sta definendo. La funzione va quindi chiamata all'interno di una sezione di definizione. Si ricordi che la libreria utilizza internamente 256 valori per rappresentare una rotazione completa (gli angoli sono quindi espressi in byte-gradi). La corrispondenza con i gradi sessagesimali è riportata nella seguente tabella: gradi sessagesimali 0 22.5 45 90 180 270 --------------------------------------------------------------- byte gradi 0 16 32 64 128 192 ----------------------------------------------------------------------------- gfx3d.library/GFXDiv SINTASSI result = GFXDiv (value1, value2) D0 D1 D0 SCOPO Questa funzione restituisce il quoziente di due numeri reali (rappresentati nel formato interno della libreria). ARGOMENTI value1 = valore in formato reale. value2 = valore in formato reale. RISULTATO result = quoziente, in formato reale, dei due numeri presenti in ingresso (value2/value1). DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXEnd SINTASSI structPtr = GFXEnd () D0 SCOPO Questa funzione termina la sezione di definizione di una struttura dati della libreria precedentemente iniziata tramite una chiamata alla funzione GFXBegin(). In caso di errore (non è stato possibile creare la struttura dati richiesta), il valore ritornato è GFX_NULL. RISULTATO structPtr = puntatore alla struttura dati creata. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXBegin(). ----------------------------------------------------------------------------- gfx3d.library/GFXEnvironment SINTASSI GFXEnvironment (envptr) A0 SCOPO Questa funzione associa una struttura Environment alla struttura Camera che si sta definendo. ARGOMENTI envptr = puntatore ad una struttura Environment precedentemente definita. DISCUSSIONE Questa funzione viene utilizzata per definire l'ambiente in cui opera la telecamera. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura Camera. Sono possibili più viste di uno stesso ambiente, implementabili da diverse telecamere operanti tutte sul medesimo ambiente. ----------------------------------------------------------------------------- gfx3d.library/GFXFarClip SINTASSI GFXFarClip (distance) D0 SCOPO Questa funzione setta la massima distanza a cui è visualizzabile la struttura dati che si sta definendo. ARGOMENTI distance = valore intero rappresentante la distanza massima dalla telecamera. DISCUSSIONE Questa funzione viene utilizzata per definire la massima distanza a cui è ancora visualizzabile la struttura dati che si sta definendo. La funzione va quindi chiamata all'interno di una sezione di definizione. ----------------------------------------------------------------------------- gfx3d.library/GFXFeatures SINTASSI features = GFXFeatures () D0 SCOPO Questa funzione restituisce le funzionalità supportate dalla libreria, rispetto alla versione 1.0. RISULTATO features = valore intero senza segno i cui bit, se settati, indicano le funzionalità supportate. DISCUSSIONE Tramite questa funzione, il task può 'interrogare' la libreria, al fine di conoscere quali funzionalità sono supportate e quali no, decidendo eventualmente quali scelte adottare. Attualmente (gfx3d.library v2.0), sono definiti i seguenti bit: - GFX_FPU_SUPP indica che la libreria supporta il coprocessore matematico nei calcoli, al posto della matematica in virgola fissa. - GFX_FLAT_SHADING_SUPP indica che la libreria è in grado di eseguire il flat shading. - GFX_DEPTH_CUEING_SUPP indica che la libreria è in grado di eseguire il depth cueing. Naturalmente, nella stessa versione della libreria l'unico flag che può variare è quello relativo al supporto dell'unità matematica, per potersi adattare al tipo di CPU+FPU installate nel sistema. Ad esempio, il seguente codice esegue un test sulla FPU: if ( GFXFeatures() & GFX_FPU_SUPP ) { /* in questo caso si devono utilizzare le funzioni */ /* di supporto matematico offerte dalla libreria */ /* (formato utilizzato = dipende dalla FPU) */ } else { /* in questo caso, invece, è consentito (ma non */ /* consigliato) manipolare direttamente i valori */ /* reali (formato utilizzato = virgola fissa 16+16) */ } La costante GFX_DEPTH_SHADING_SUPP ha il medesimo significato della costante GFX_DEPTH_CUEING_SUPP. ----------------------------------------------------------------------------- gfx3d.library/GFXFix SINTASSI result = GFXFix (value) D0 D0 SCOPO Questa funzione consente di trasformare un valore reale, rappresentato nel formato interno della libreria, nel corrispettivo valore intero. ARGOMENTI value = valore reale. RISULTATO result = valore intero. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXFixMul SINTASSI result = GFXFixMul (integer, real) D0 D1 D0 SCOPO Questa funzione consente di moltiplicare un valore reale per un valore intero, ottenendo come risultato un valore reale. ARGOMENTI integer = valore intero. real = valore reale. RISULTATO result = valore reale. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXFixSqrt SINTASSI result = GFXFixSqrt (value) D0 D0 SCOPO Questa funzione consente di calcolare la radice quadrata di un valore intero, ottenendo come risultato sempre un valore intero. ARGOMENTI value = valore intero. RISULTATO result = valore intero. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXFlt SINTASSI result = GFXFlt (value) D0 D0 SCOPO Questa funzione consente di trasformare un valore intero nel corrispettivo valore reale, rappresentato nel formato interno della libreria. ARGOMENTI value = valore intero. RISULTATO result = valore reale. DISCUSSIONE L'attuale versione della libreria gfx3d.library rappresenta i numeri reali nel formato in virgola fissa a 32 bit, utilizzando i 16 bit più significativi per rappresentare la parte intera, i 16 bit meno significativi per rappresentare la parte frazionaria. Questo formato consente di velocizzare l'esecuzione del codice nei processori che non sono forniti di coprocessore matematico (come, ad esempio, i Motorola 68020 e 68030), a scapito, però, della precisione dei risultati. Future versioni della libreria saranno sicuramente in grado di utilizzare il coprocessore matematico presente nelle più moderne CPU. Per evitare problemi di incompatibilità con le future versioni, si raccomanda di utilizzare le funzioni di supporto matematico fornite dalla libreria stessa. Nel caso si preferisca comunque immettere direttamente i valori reali nelle funzioni che ne richiedono, si raccomanda di 'interrogare' la libreria stessa tramite la funzione GFXFeatures(), al fine di ottenere il formato interno utilizzato dalla particolare versione della libreria. ----------------------------------------------------------------------------- gfx3d.library/GFXFltMul SINTASSI result = GFXFltMul (real, integer) D0 D1 D0 SCOPO Questa funzione consente di moltiplicare un valore intero per un valore reale, ottenendo come risultato un valore intero. ARGOMENTI real = valore reale. integer = valore intero. RISULTATO result = valore intero. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXFocus SINTASSI GFXFocus (focus) D0 SCOPO Questa funzione definisce la distanza focale da associare alla telecamera che si sta definendo. ARGOMENTI focus = distanza focale da associare alla telecamera. Deve essere un valore intero >0. DISCUSSIONE Questa funzione viene utilizzata per definire la distanza focale della telecamera che si sta definendo. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura Camera. La distanza focale influenza la prospettiva della scena visualizzata. ----------------------------------------------------------------------------- gfx3d.library/GFXFrame SINTASSI GFXFrame (frameptr) A0 SCOPO Questa funzione associa un fotogramma all'oggetto che si sta definendo. ARGOMENTI frameptr = puntatore ad una struttura Frame precedentemente creata. DISCUSSIONE Questa funzione viene utilizzata per associare il fotogramma iniziale di un oggetto. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura Object. Questa implementazione consente di ottenere due funzionalità principali. Per prima cosa, c'è un notevole risparmio di memoria in presenza di più oggetti tutti uguali. E' necessario infatti definire un solo fotogramma, per poi assegnarlo ad ogni oggetto in questione. La seconda funzione ottenibile è l'animazione per fotogrammi, implementabile tramite la funzione GFXModifyObjectFrame(). In questo caso è necessario però che il fotogramma assegnato inizialmente tramite la funzione GFXFrame() sia quello, tra i vari fotogrammi appartenenti all'animazione, con il maggior numero di vertici e di poligoni, in quanto tali valori sono necessari per il corretto dimensionamento della memoria allocata per la struttura Camera. ----------------------------------------------------------------------------- gfx3d.library/GFXFreeMem SINTASSI GFXFreeMem (memptr) A0 SCOPO Questa funzione dealloca un quantitativo di memoria pubblica del sistema precedentemente allocato tramite la funzione GFXAllocMem(); ARGOMENTI memptr = indirizzo del blocco di memoria da deallocare. DISCUSSIONE Nel caso sia necessario deallocare un blocco di memoria precedentemente allocato dal task tramite la funzione GFXAllocMem(), tale risultato si ottiene tramite la funzione GFXFreeMem(). Non è consentito deallocare la memoria in questione con le funzioni fornite dal sistema operativo. Si faccia anche riferimento alla discussione relativa la funzione GFXAllocMem(). ----------------------------------------------------------------------------- gfx3d.library/GFXHeight SINTASSI GFXHeight (height) D0 SCOPO Questa funzione definisce l'altezza in pixel della visuale fornita dalla telecamera che si sta definendo. ARGOMENTI height = altezza in pixel della visuale fornita dalla Camera. DISCUSSIONE Questa funzione viene utilizzata per definire l'altezza della visuale della telecamera che si sta definendo. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura Camera. La dimensione dell'altezza di schermo deve essere compresa tra 1 e 200 pixels. Si faccia anche riferimento alla discussione relativa la funzione GFXWidth(). ----------------------------------------------------------------------------- gfx3d.library/GFXModifyCameraAspectRatio SINTASSI GFXModifyCameraAspectRatio (camera, ratiox, ratioy, ratioz) A0 D0 D1 D2 SCOPO Questa funzione modifica il fattore moltiplicativo di una telecamera. ARGOMENTI camera = puntatore ad una struttura Camera precedentemente creata. ratiox = valore reale per cui moltiplicare le coordinate X dei vertici presenti nella scena prima della proiezione a video. ratioy = valore reale per cui moltiplicare le coordinate Y dei vertici presenti nella scena prima della proiezione a video. ratioz = valore reale per cui moltiplicare le coordinate Z dei vertici presenti nella scena prima della proiezione a video. DISCUSSIONE Questa funzione consente di modificare dinamicamente l'aspetto della scena visualizzata dalla telecamera. Si faccia anche riferimento alla discussione relativa la funzione GFXAspectRatio(). ----------------------------------------------------------------------------- gfx3d.library/GFXModifyCameraDirection SINTASSI GFXModifyCameraDirection (camera, ax, ay, az) A0 D0 D1 D2 SCOPO Questa funzione modifica la direzione di vista di una telecamera. ARGOMENTI camera = puntatore ad una struttura Camera precedentemente creata. ax = valore intero esprimente l'angolo di rotazione attorno l'asse X. ay = valore intero esprimente l'angolo di rotazione attorno l'asse Y. az = valore intero esprimente l'angolo di rotazione attorno l'asse Z. DISCUSSIONE Questa funzione consente di modificare dinamicamente la direzione di vista di una telecamera. Si faccia anche riferimento alla discussione relativa la funzione GFXDirection(). ----------------------------------------------------------------------------- gfx3d.library/GFXModifyCameraFocus SINTASSI GFXModifyCameraFocus (camera, focus) A0 D0 SCOPO Questa funzione modifica la distanza focale di una telecamera. ARGOMENTI camera = puntatore ad una struttura Camera precedentemente creata. focus = nuova distanza focale della telecamera. Deve essere un valore intero >0. DISCUSSIONE La distanza focale influenza la prospettiva della scena visualizzata. ----------------------------------------------------------------------------- gfx3d.library/GFXModifyCameraHeight SINTASSI GFXModifyCameraHeight (camera, height) A0 D0 SCOPO Questa funzione modifica dinamicamente l'altezza in pixel della visuale fornita da una telecamera. ARGOMENTI camera = puntatore ad una struttura Camera precedentemente creata. height = nuova altezza in pixel della visuale fornita dalla Camera. DISCUSSIONE La dimensione dell'altezza di schermo deve essere compresa tra 1 e 200 pixels. ----------------------------------------------------------------------------- gfx3d.library/GFXModifyCameraPosition SINTASSI GFXModifyCameraPosition (camera, x, y, z) A0 D0 D1 D2 SCOPO Questa funzione modifica la posizione di una telecamera. ARGOMENTI camera = puntatore ad una struttura Camera precedentemente creata. x = valore intero esprimente la nuova posizione sull'asse X. y = valore intero esprimente la nuova posizione sull'asse Y. z = valore intero esprimente la nuova posizione sull'asse Z. DISCUSSIONE Questa funzione consente di modificare dinamicamente la posizione di una telecamera. Si faccia anche riferimento alla discussione relativa la funzione GFXPosition(). ----------------------------------------------------------------------------- gfx3d.library/GFXModifyCameraVideoBuffer SINTASSI GFXModifyCameraVideoBuffer (camera, vidbuff) A0 A1 SCOPO Questa funzione modifica l'indirizzo dello schermo video di una telecamera. ARGOMENTI camera = puntatore ad una struttura Camera precedentemente creata. vidbuff = puntatore alla bitmap dell'uscita video di una telecamera. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXVideoBuffer(). ----------------------------------------------------------------------------- gfx3d.library/GFXModifyCameraWidth SINTASSI GFXModifyCameraWidth (camera, width) A0 D0 SCOPO Questa funzione modifica dinamicamente la larghezza in pixel della visuale fornita da una telecamera. ARGOMENTI camera = puntatore ad una struttura Camera precedentemente creata. width = nuova larghezza in pixel della visuale fornita dalla Camera. DISCUSSIONE La dimensione della larghezza di schermo deve essere compresa tra 32 e 320 pixels, e deve essere un multiplo di 32 pixel. ----------------------------------------------------------------------------- gfx3d.library/GFXModifyObjectDirection SINTASSI GFXModifyObjectDirection (object, ax, ay, az) A0 D0 D1 D2 SCOPO Questa funzione modifica l'orientamento di un oggetto. ARGOMENTI object = puntatore ad una struttura Object precedentemente creata. ax = valore intero esprimente l'angolo di rotazione attorno l'asse X dell'oggetto. ay = valore intero esprimente l'angolo di rotazione attorno l'asse Y dell'oggetto. az = valore intero esprimente l'angolo di rotazione attorno l'asse Z dell'oggetto. DISCUSSIONE Questa funzione consente di modificare dinamicamente l'orientamento di un oggetto. Si faccia anche riferimento alla discussione relativa la funzione GFXDirection(). ----------------------------------------------------------------------------- gfx3d.library/GFXModifyObjectFrame SINTASSI GFXModifyObjectFrame (object, frame) A0 A1 SCOPO Questa funzione modifica dinamicamente il fotogramma di un oggetto. ARGOMENTI object = puntatore ad una struttura Object precedentemente creata. frame = puntatore ad una struttura Frame precedentemente creata. DISCUSSIONE Tramite questa funzione è possibile implementare un'animazione a fotogrammi di un oggetto. Si faccia anche riferimento alla discussione relativa la funzione GFXFrame(). ----------------------------------------------------------------------------- gfx3d.library/GFXModifyObjectPosition SINTASSI GFXModifyObjectPosition (object, x, y, z) A0 D0 D1 D2 SCOPO Questa funzione modifica la posizione di un oggetto. ARGOMENTI object = puntatore ad una struttura Object precedentemente creata. x = valore intero esprimente la nuova posizione sull'asse X. y = valore intero esprimente la nuova posizione sull'asse Y. z = valore intero esprimente la nuova posizione sull'asse Z. DISCUSSIONE Questa funzione consente di modificare dinamicamente la posizione di un oggetto. Si faccia anche riferimento alla discussione relativa la funzione GFXPosition(). ----------------------------------------------------------------------------- gfx3d.library/GFXMul SINTASSI result = GFXMul (value1, value2) D0 D1 D0 SCOPO Questa funzione restituisce il prodotto di due numeri reali (rappresentati nel formato interno della libreria). ARGOMENTI value1 = valore in formato reale. value2 = valore in formato reale. RISULTATO result = prodotto, in formato reale, dei due numeri presenti in ingresso. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXNearClip SINTASSI GFXNearClip (distance) D0 SCOPO Questa funzione setta la minima distanza a cui è visualizzabile l'oggetto che si sta definendo. ARGOMENTI distance = valore intero rappresentante la distanza minima dalla telecamera. DISCUSSIONE Questa funzione viene utilizzata per definire la minima distanza a cui è ancora visualizzabile l'oggetto che si sta definendo. La funzione va quindi chiamata all'interno della sezione di definizione di un oggetto. Normalmente, si pone tale distanza al valore -focus+1, dove focus è la distanza focale della telecamera. ----------------------------------------------------------------------------- gfx3d.library/GFXNeg SINTASSI result = GFXNeg (value) D0 D0 SCOPO Questa funzione restituisce il negato del valore reale (rappresentato nel formato interno della libreria) dato in ingresso. ARGOMENTI value = valore in formato reale. RISULTATO result = valore in formato reale. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXObject SINTASSI GFXObject (objptr) A0 SCOPO Questa funzione aggiunge un oggetto ad un ambiente. ARGOMENTI objptr = puntatore ad una struttura Object precedentemente creata. DISCUSSIONE Questa funzione viene utilizzata per aggiungere un oggetto ad un ambiente. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura Environment. E' importante che l'associazione oggetto-ambiente sia biunivoca, cioè che un oggetto appartenga ad un solo ambiente, il quale sia il solo a contenere tale oggetto. Nel caso sia necessario associare l'oggetto anche ad un altro ambiente, si dovrà creare un oggetto simile al primo (si può utilizzare anche lo stesso fotogramma puntato dal primo), per assegnarlo poi al secondo ambiente. ----------------------------------------------------------------------------- gfx3d.library/GFXPalette SINTASSI GFXPalette (paletteptr) A0 SCOPO Questa funzione setta la palette di riferimento per una struttura delle sfumature dei colori. ARGOMENTI paletteptr = puntatore ad una struttura Palette inizializzata esternamente. DISCUSSIONE Questa funzione viene utilizzata per settare la palette dei colori di riferimento per la struttura adibita a calcolare le sfumature dei colori. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura ShadeTable. ----------------------------------------------------------------------------- gfx3d.library/GFXPi SINTASSI result = GFXPi () D0 SCOPO Questa funzione restituisce il numero pi-greco, utile nelle funzioni trigonometriche. RISULTATO result = valore reale ( 3.141592654... ). DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXPolygon SINTASSI GFXPolygon (polyptr) A0 SCOPO Questa funzione aggiunge un poligono ad un fotogramma. ARGOMENTI polyptr = puntatore ad una struttura Polygon precedentemente creata. DISCUSSIONE Questa funzione viene utilizzata per aggiungere un poligono ad un fotogramma. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura Frame. IMPORTANTE Dalla versione 2.4 della libreria, una volta aggiunto il poligono al frame, la struttura dati del poligono viene deallocata dalla memoria. ----------------------------------------------------------------------------- gfx3d.library/GFXPosition SINTASSI GFXPosition (x, y, z) D0 D1 D2 SCOPO Questa funzione definisce la posizione da associare alla struttura dati che si sta definendo. ARGOMENTI x = valore intero esprimente la posizione sull'asse X. y = valore intero esprimente la posizione sull'asse Y. z = valore intero esprimente la posizione sull'asse Z. DISCUSSIONE Questa funzione viene utilizzata per definire la posizione da associare alla struttura dati che si sta definendo. La funzione va quindi chiamata all'interno di una sezione di definizione. ----------------------------------------------------------------------------- gfx3d.library/GFXSetColor SINTASSI GFXSetColor (color) D0 SCOPO Questa funzione definisce il colore di default per le successive definizioni di strutture dati. ARGOMENTI color = colore di default. DISCUSSIONE Questa funzione viene utilizzata per definire il colore di default da associare alle successive strutture dati da definire. Di conseguenza, tale funzione viene invocata all'esterno delle sezioni di definizione. Ad esempio, il seguente codice definisce due poligoni aventi lo stesso colore: GFXBegin( GFX_POLYGON ); GFXColor( col ); GFXVertex( x0, y0, z0 ); GFXVertex( x1, y1, z1 ); GFXVertex( x2, y2, z2 ); poly1 = GFXEnd(); GFXBegin( GFX_POLYGON ); GFXColor( col ); GFXVertex( x3, y3, z3 ); GFXVertex( x4, y4, z4 ); GFXVertex( x5, y5, z5 ); poly2 = GFXEnd(); mentre, il seguente codice esegue la medesima cosa: GFXSetColor( col ); GFXBegin( GFX_POLYGON ); GFXVertex( x0, y0, z0 ); GFXVertex( x1, y1, z1 ); GFXVertex( x2, y2, z2 ); poly1 = GFXEnd(); GFXBegin( GFX_POLYGON ); GFXVertex( x3, y3, z3 ); GFXVertex( x4, y4, z4 ); GFXVertex( x5, y5, z5 ); poly2 = GFXEnd(); ----------------------------------------------------------------------------- gfx3d.library/GFXSetFarClip SINTASSI GFXSetFarClip (distance) D0 SCOPO Questa funzione setta di default la massima distanza a cui saranno visualizzabili le successive strutture dati da definire. ARGOMENTI distance = valore intero rappresentante la distanza massima dalla telecamera. DISCUSSIONE Questa funzione viene utilizzata per definire la massima distanza di default a cui saranno ancora visualizzabili le successive strutture dati da definire. Di conseguenza, tale funzione viene invocata all'esterno delle sezioni di definizione. ----------------------------------------------------------------------------- gfx3d.library/GFXSetNearClip SINTASSI GFXSetNearClip (distance) D0 SCOPO Questa funzione setta di default la minima distanza a cui saranno visualizzabili le successive strutture dati da definire. ARGOMENTI distance = valore intero rappresentante la distanza minima dalla telecamera. DISCUSSIONE Questa funzione viene utilizzata per definire la minima distanza di default a cui saranno ancora visualizzabili le successive strutture dati da definire. Di conseguenza, tale funzione viene invocata all'esterno delle sezioni di definizione. ----------------------------------------------------------------------------- gfx3d.library/GFXSetShading SINTASSI GFXSetShading (shading) D0 SCOPO Questa funzione definisce il tipo di ombreggiatura di default per le successive definizioni di strutture dati. ARGOMENTI shading = tipo di ombreggiatura. DISCUSSIONE Questa funzione viene utilizzata per definire il tipo di ombreggiatura di default da associare alle successive strutture dati da definire. Di conseguenza, tale funzione viene invocata all'esterno delle sezioni di definizione. ----------------------------------------------------------------------------- gfx3d.library/GFXShadeTable SINTASSI GFXShadeTable (shtptr) A0 SCOPO Questa funzione setta la tabella delle sfumature per l'ambiente che si sta definendo. ARGOMENTI shtptr = puntatore ad una struttura ShadeTable precedentemente creata. DISCUSSIONE Questa funzione viene utilizzata per settare la tabella delle sfumature dei colori per l'ambiente che si sta definendo. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura Environment. ----------------------------------------------------------------------------- gfx3d.library/GFXShading SINTASSI GFXShading (shading) D0 SCOPO Questa funzione definisce il tipo di ombreggiatura per il poligono che si sta definendo. ARGOMENTI shading = tipo di ombreggiatura: - GFX_FILL_SHADING - GFX_FLAT_SHADING - GFX_DEPTH_CUEING DISCUSSIONE Questa funzione viene utilizzata per settare il tipo di ombreggiatura da associare al poligono che si sta definendo. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura Polygon. Il valore GFX_DEPTH_SHADING ha il medesimo significato di GFX_DEPTH_CUEING. ----------------------------------------------------------------------------- gfx3d.library/GFXShareWorkBuffer SINTASSI GFXShareWorkBuffer (cameraptr) A0 SCOPO Questa funzione permette di condividere lo stesso buffer di lavoro con più telecamere. ARGOMENTI cameraptr = puntatore ad una struttura Camera precedentemente creata. DISCUSSIONE Questa funzione permette la condivisione di un solo buffer di lavoro con diverse telecamere. La funzione va chiamata all'interno della sezione di definizione di una struttura Camera. La struttura che si sta definendo avrà così lo stesso work buffer condiviso con la struttura specificata nel parametro di ingresso. La dimensione del work buffer deve essere sufficiente per la telecamera destinazione, in quanto la libreria non effettua alcun controllo preventivo. ----------------------------------------------------------------------------- gfx3d.library/GFXSin SINTASSI value = GFXSin (angle) D0 D0 SCOPO Questa funzione restituisce il seno dell'angolo dato in ingresso. ARGOMENTI angle = valore reale esprimente l'angolo in radianti. RISULTATO result = valore reale esprimente il seno dell'angolo dato. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXSqrt SINTASSI result = GFXSqrt (value) D0 D0 SCOPO Questa funzione consente di calcolare la radice quadrata di un valore reale. ARGOMENTI value = valore reale. RISULTATO result = valore reale. DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXSteps SINTASSI GFXSteps (steps) D0 SCOPO Questa funzione definisce il numero di sfumature per colore da assegnare alla tabella delle sfumature che si sta definendo. ARGOMENTI steps = numero di sfumature per passare da un colore ad un altro. DISCUSSIONE Questa funzione viene utilizzata per definire il numero di sfumature nel passare da un colore ad un altro. La funzione va chiamata all'interno della sezione di definizione di una struttura ShadeTable. ----------------------------------------------------------------------------- gfx3d.library/GFXSub SINTASSI result = GFXSub (value1, value2) D0 D1 D0 SCOPO Questa funzione restituisce la sottrazione di due numeri reali (rappresentati nel formato interno della libreria). ARGOMENTI value1 = valore in formato reale. value2 = valore in formato reale. RISULTATO result = differenza dei due numeri presenti in ingresso (value2-value1). DISCUSSIONE Si faccia riferimento alla discussione relativa la funzione GFXFlt(). ----------------------------------------------------------------------------- gfx3d.library/GFXThreshold SINTASSI GFXThreshold (threshold) D0 SCOPO Questa funzione definisce la soglia alla quale fermarsi nella sfumatura da un colore ad un altro. ARGOMENTI threshold = valore di soglia riferito al numero di passi. DISCUSSIONE Questa funzione viene utilizzata per definire il valore di soglia alla quale fermarsi nella sfumatura da un colore ad un altro. La funzione va chiamata all'interno della sezione di definizione di una struttura ShadeTable. La soglia permette di selezionare solo una parte del range di sfumatura fra due colori. ESEMPIO Bianco Nero |--------|--------|--------|--------|--------|--------|--------> 0 1 2 3 4 5 6 7 In questo caso, la sfumatura dal bianco al nero utilizza 7 passaggi ( quindi, è stata eseguita la chiamata GFXSteps( 7 ) ). Utilizzando invece un valore di soglia, la sfumatura completa non termina più al colore nero, ma ad un colore intermedio: Bianco Grigio |--------|--------|--------|--------> 0 1 2 3 4 ( In questo caso, è stata eseguita la chiamata GFXThreshold( 4 ) dopo l'invocazione della funzione GFXSteps() ). ----------------------------------------------------------------------------- gfx3d.library/GFXUpdateScene SINTASSI GFXUpdateScene (cameraptr) A0 SCOPO Questa funzione aggiorna la scena visualizzata dalla telecamera, scrivendo il risultato nel buffer di lavoro. ARGOMENTI cameraptr = puntatore ad una struttura Camera. DISCUSSIONE Questa è la funzione principale della libreria. Tale funzione si occupa infatti di aggiornare tutti i parametri della scena (quali la posizione dei vari oggetti, la loro direzione, ecc...) e della telecamera (distanza focale, aspetto visivo, ecc...). Successivamente, la funzione si occupa di scrivere il risultato sul work buffer. E' compito del task sincronizzare l'uscita video tramite la funzione GFXUpdateVideoBuffer(). ----------------------------------------------------------------------------- gfx3d.library/GFXUpdateVideoBuffer SINTASSI GFXUpdateVideoBuffer () SCOPO Questa funzione si occupa di aggiornare il buffer video con il contenuto del buffer di lavoro. DISCUSSIONE Normalmente, tale funzione viene invocata dopo la funzione GFXUpdateScene(). Tale funzione rende infatti di default il work buffer ed il video buffer della camera da visualizzare. E' compito del task sincronizzare l'uscita video tramite la funzione GFXUpdateVideoBuffer(). ----------------------------------------------------------------------------- gfx3d.library/GFXVersion SINTASSI result = GFXVersion () D0 SCOPO Questa funzione restituisce la versione e la revisione corrente della libreria. RISULTATO result = risultato richiesto. DISCUSSIONE Tramite questa funzione il task può conoscere il numero di versione e di revisione della libreria. Il numero di versione viene restituito nella parte alte del risultato, il numero di revisione viene restituito nella parte bassa del risultato. ----------------------------------------------------------------------------- gfx3d.library/GFXVertex SINTASSI GFXVertex (x, y, z) D0 D1 D2 SCOPO Questa funzione definisce un vertice di un poligono. ARGOMENTI x = valore intero rappresentante la coordinata sull'asse X. y = valore intero rappresentante la coordinata sull'asse Y. z = valore intero rappresentante la coordinata sull'asse Z. DISCUSSIONE Questa funzione viene utilizzata per definire un vertice del poligono che si sta definendo. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura Polygon. Attualmente, non sono supportati poligoni composti da più di tre vertici, quindi eventuali vertici definiti in più sono ignorati. La libreria segue la regola della mano destra, quindi, affinchè un poligono sia visualizzabile, i vertici devono descrivere a video un percorso antiorario. Eventuali poligoni aventi entrambe le facce visibili devono essere specificati come due strutture Polygon distinte. ----------------------------------------------------------------------------- gfx3d.library/GFXVideoBuffer SINTASSI GFXVideoBuffer (videoptr) A0 SCOPO Questa funzione associa il buffer video alla struttura Camera che si sta definendo. ARGOMENTI videoptr = puntatore al video buffer. DISCUSSIONE Questa funzione viene utilizzata per definire il buffer video di una telecamera. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura Camera. Attualmente, il video buffer deve essere un blocco contiguo di chip ram (che deve essere quindi allocato e deallocato esternamente dal task) delle dimensioni di LARGHEZZAxALTEZZA bytes. L'indirizzo del video buffer coincide con il puntatore al primo bitplane (#0) della bitmap di destinazione, a cui segue il secondo (#1), il terzo(#2) e così via fino all'ottavo bitplane (#7). ----------------------------------------------------------------------------- gfx3d.library/GFXWidth SINTASSI GFXWidth (width) D0 SCOPO Questa funzione definisce la larghezza in pixel della visuale fornita dalla telecamera che si sta definendo. ARGOMENTI width = larghezza in pixel della visuale fornita dalla Camera. DISCUSSIONE Questa funzione viene utilizzata per definire la larghezza della visuale della telecamera che si sta definendo. La funzione va quindi chiamata all'interno della sezione di definizione di una struttura Camera. La dimensione della larghezza di schermo deve essere compresa tra 32 e 320 pixels, e deve essere multipla di 32 pixels. Si faccia anche riferimento alla discussione relativa la funzione GFXHeight(). ----------------------------------------------------------------------------- gfx3d.library/GFXWritePixel SINTASSI GFXWritePixel (x, y, color) D0 D1 D2 SCOPO Questa funzione scrive un pixel nel buffer di lavoro corrente. ARGOMENTI x = coordinata orizzontale del pivel sul video. y = coordinata verticale del pixel sul video. color = colore del pixel. DISCUSSIONE Questa funzione permette al task di scrivere un pixel nel work buffer corrente. Eventuali punti eccedenti le dimensioni correnti dello schermo sono ricondotti ai margini del video. Si tenga presente che la libreria considera l'origine delle coordinate al centro dello schermo. Le coordinate estreme del video sono quindi: -WIDTH/2 <= x <= -(WIDTH/2)-1 -HEIGHT/2 <= y <= -(HEIGHT/2)-1 -----------------------------------------------------------------------------